---
title: Add to an existing repository
description: Using Turborepo with your existing repository
---

import { Tabs, Tab } from '#/components/tabs';
import { Callout } from '#/components/callout';
import { Step, Steps } from '#/components/steps';

Turborepo can be incrementally adopted in **any repository, single or multi-package**, to speed up the developer and CI workflows of the repository.

After installing `turbo` and configuring your tasks in `turbo.json`, you'll notice how [caching](/repo/docs/crafting-your-repository/caching) helps you run tasks much faster.

## Preparing a single-package workspace

A [single-package workspace](https://vercel.com/docs/vercel-platform/glossary#single-package-workspace) is, for example, what you get after running `npx create-next-app` or `npm create vite`. You don't need to do any extra work for Turborepo to handle your repo so you can jump to the first step below.

To learn more about Turborepo in single-package workspaces, visit [the dedicated guide](/repo/docs/guides/single-package-workspaces).

## Preparing a multi-package workspace (monorepo)

`turbo` is built on top of Workspaces, a feature of the major package managers in the JavaScript ecosystem. This makes it easy to adopt in your existing codebase.

<Callout type="good-to-know">
  If you're finding that `turbo` is having issues like not being able to
  discover packages in your workspace or not following your dependency graph,
  visit our [Structuring a
  repository](/repo/docs/crafting-your-repository/structuring-a-repository) page
  for tips.
</Callout>

Note that you don't have to start running _all_ your tasks for _all_ your
packages using `turbo` right away. You can start with a single task in just a
few packages and incrementally add more tasks and packages as you get more
familiar with Turborepo.

## Adding Turborepo to your repository

<Steps>
<Step>
### Install `turbo`

We recommend you install `turbo` both globally and into your repository's root for the best developer experience.

<Tabs items={['npm', 'yarn', 'pnpm']} storageKey="selected-pkg-manager">
  <Tab value="npm">

    ```bash title="Terminal"
    # Global install
    npm install turbo --global
    # Install in repository
    npm install turbo --save-dev
    ```

  </Tab>
  <Tab value="yarn">

    ```bash title="Terminal"
    # Global install
    yarn global add turbo
    # Install in repository
    yarn add turbo --dev
    ```

  </Tab>
  <Tab value="pnpm">

    ```bash title="Terminal"
    # Global install
    pnpm add turbo --global
    # Install in repository
    pnpm add turbo --save-dev
    ```

  </Tab>
</Tabs>

To learn more about why we recommend both installations, visit the [Installation page](/repo/docs/getting-started/installation).

</Step>
<Step>

### Add a `turbo.json` file

In the root of your repository, create a `turbo.json` file.

We'll be using `build` and `check-types` tasks in this guide but you can replace these with other tasks that interest you, like `lint` or `test`.

<Tabs items={['Next.js', 'Vite']} storageKey="framework-preference">
  <Tab value="Next.js">
```json title="./turbo.json"
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "check-types": {
      "dependsOn": ["^check-types"]
    },
    "dev": {
      "persistent": true,
      "cache": false
    }
  }
}
```

For more information on configuring your `turbo.json`, see the [Configuration Options](/repo/docs/reference/configuration) documentation.

In your Next.js application, make sure you have a `check-types` script for `turbo` to run.

```diff title="apps/web/package.json"
{
  "scripts": {
+   "check-types": "tsc --noEmit"
  }
}
```

  </Tab>
  <Tab value="Vite">
```json title="./turbo.json"
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "outputs": ["dist/**"]
    },
    "check-types": {
      "dependsOn": ["^check-types"]
    },
    "dev": {
      "persistent": true,
      "cache": false
    }
  }
}
```

Some Vite starters ship with a `package.json` that looks like this:

```json title="package.json"
{
  "scripts": {
    "build": "tsc && vite build"
  }
}
```

We recommend splitting these into a `check-types` and `build` script so that `turbo` can run them in parallel.

```json title="apps/web/package.json"
{
  "scripts": {
    "build": "vite build",
    "check-types": "tsc --noEmit"
  }
}
```

  </Tab>
</Tabs>

In a multi-package workspace, you may also want to add a `check-types` script
to one or more of your library packages to see how multiple scripts across
different packages run with one `turbo` command.

</Step>
<Step>
### Edit `.gitignore`

Add `.turbo` to your `.gitignore` file. The `turbo` CLI uses these folders for persisting logs, outputs, and other functionality.

```diff title=".gitignore"
+ .turbo
```

</Step>
<Step>
### Run the `build` and `check-types` tasks with `turbo`

```bash title="Terminal"
turbo build check-types
```

This runs `build` and `check-types` at the same time.

</Step>
<Step>
**Without making any changes to the code, try running `build` and `check-types` again:**

```bash title="Terminal"
turbo check-types build
```

You should see terminal output like this:

```bash title="Terminal"
 Tasks:    2 successful, 2 total
Cached:    2 cached, 2 total
  Time:    185ms >>> FULL TURBO
```

Congratulations! **You just built and type checked your code in milliseconds**.

To learn more about how `turbo` makes this possible, check out [the caching documentation](/repo/docs/crafting-your-repository/caching).

</Step>
<Step>

### Begin developing by running `dev` with `turbo`

In a multi-package workspace, you can run `turbo dev` to start the development tasks for all your packages at once.

```bash title="Terminal"
turbo dev
```

You can also [use a filter](/repo/docs/crafting-your-repository/running-tasks#using-filters) to focus on a specific package and its dependencies.

<Callout type="info">
Note that this step doesn't provide much value in a single-package workspace since:

- You don't cache the outputs for a development task.
- There's only one development script so there's nothing to run in parallel.

</Callout>

</Step>

<Step>

## Next steps

You now up and running with Turborepo! To learn about more ways you can improve your workflow and get the most out of `turbo`, we recommend checking out the following pages:

- [Enabling Remote Caching for development machines](/repo/docs/crafting-your-repository/constructing-ci#enabling-remote-caching)
- [Enabling Remote Caching in CI](/repo/docs/crafting-your-repository/constructing-ci)
- [Handling environment variables](/repo/docs/crafting-your-repository/using-environment-variables)
- [Filtering tasks](/repo/docs/reference/run#--filter-string)

</Step>
</Steps>
